feat(api): MCP OAuth authorization server, RFC-0044 phase 2 (#144) - #176

RFC-0044 Phase 2: the deployment runs its own OAuth 2.1 authorization server, so the discovery documents from #152 now point at something that works. Refs #144. Registration (CIMD, DCR), "Connected agents", McpClientSetup, the guides and the e2e test stay in Phase 3.

Scope → code and tests

Deviations from the RFC (and why)

1. Consent goes through Cloudhal, not authClient.oauth2.consent. Studio posts to POST /api/agent-grants/consent, which narrows, caps the mode, calls the provider's /oauth2/consent server-side and then writes grant + agent_owner + audit. The provider only accepts consent scopes that are a subset of the request, so content:write → content:write:own cannot be expressed there; the token therefore carries the requested scopes the member kept and the grant row is the cap (principal = narrow(narrow(token.scope, grant.scopes), roleScopes(role)), §5 wrote intersect, which would drop the :own variant). The provider's own /oauth2/consent is fenced in createApi and refuses any HTTP caller without a per-instance server key.
2. Provider endpoints fenced (more conservative than §2's table): only /oauth2/authorize, /oauth2/token, /oauth2/revoke and /jwks are reachable over HTTP. Client and consent CRUD, introspection, userinfo, registration (Phase 3) and the jwt() plugin's session-JWT /api/auth/token answer 404; jwt({ disableSettingJwtHeader: true }). clientPrivileges admits only the server's own calls.
3. Pre-registered test client. Phase 2 has no registration endpoint, so tests use OauthServer.createClient (server-side only, no route); the workerd test writes the client row the way the provider stores it.
4. /api/agent-grants ships list, revoke and consent only; PATCH :id (mode) and the elevation endpoints come with "Connected agents" in Phase 3. A new consent for the same client replaces scopes and mode and ends a stored elevation.
5. Consent memory (Decision 8) is the provider's: a subset of granted scopes skips the screen and, in Phase 2, writes no audit row.
6. jose pinned to 6.2.12, not the newest 6.2.15: better-auth's own jose resolves to 6.2.12, and a second jose produced a second @better-auth/core whose types no longer matched. The pins test now guards this.
7. @better-auth/cimd not added (CIMD is Phase 3).
8. Studio template: the RFC names a form template that the design lint does not have; the screen registers a new consent template (PageLayout + SectionCards + Checkbox.Group + ModePicker + Button) and sits in the account frame.
9. CLOUDHAL_MCP_OAUTH=off switch on both runtimes (not in the RFC), and plain HTTP is accepted only on loopback (the plugin refuses a plain-HTTP resource elsewhere).
10. Member removal revokes their grants too (the principal path already refuses them through inv. 2).
11. Changesets are patch per the release instruction (the RFC said minor), for @cloudhal/storage, @cloudhal/api, @cloudhal/cloudflare, @cloudhal/cli (fixed group).
12. Cost noted: mcp() seeds its oauthResource row at init (one indexed read per Better Auth instance, so per request on Workers).
13. Shared suite file: §8 names testing-mcp-oauth.ts / test/mcp-oauth.test.ts; those keep Phase 1's discovery cases, and Phase 2's cases live next to them in testing-mcp-oauth-server.ts (+ harness) / test/mcp-oauth-server.test.ts, to stay under the size ratchet.
14. design:shots naming: the script named PNGs after the whole route, query included, so a signed consent URL overflowed the file name (ENAMETOOLONG); it now names files by the path only (apps/studio/scripts/screenshots.ts, one line).
15. Discovery and step-up from feat(api): MCP OAuth discovery on /mcp (RFC-0044 phase 1) #152/fix: review follow-ups for 0.6.5 (#168) #173 win over the RFC text: mcp-oauth.ts / mcp-mount.ts are unchanged; the plugin's own PRM handler is never reached (Hono only forwards /api/auth/*).

Decisions the RFC did not settle (conservative choice taken)

• Access tokens pinned to EdDSA in verification (no algorithm confusion); Ed25519 confirmed on workerd (cloudflare-deploy.test.ts checks the header alg: EdDSA, typ: at+jwt).
• A token principal is rate-limited like a key (600 requests per minute per connection, rate_limits).
• The admin Worker's issuer is the request's origin (as Better Auth's baseURL already is); tokens from *.workers.dev do not work on a custom domain and vice versa.

Checks run locally

All one package at a time (turbo run test --concurrency=1), D1 suites included (Miniflare ran fine locally, nothing left to CI):

• @cloudhal/storage ✅ (migrate tests on better-sqlite3, D1, do-sqlite)
• @cloudhal/api ✅ 41 files / 509 tests, incl. the new OAuth suite (30 cases: 15 × better-sqlite3, 15 × D1)
• @cloudhal/cloudflare ✅
• @cloudhal/cli ✅ 61 files / 443 tests, incl. the new workerd OAuth flow in cloudflare-deploy.test.ts (Ed25519 JWT signed in workerd, D1, consent, /mcp via the SDK client)
• @cloudhal/studio ✅ 81 files / 1305 tests (new oauth-consent.test.tsx incl. the Auto-mode consent rule, login-setup.test.ts, i18n tests after pnpm i18n:import)
• pnpm lint 0 errors (warnings are the existing backlog; resolvePrincipal's pre-existing complexity warning went 31 → 33), pnpm size:check ✅ (baseline tightened for createApi and createAdminWorker), pnpm design:lint ✅ 402 files, tsc --noEmit ✅ in api, cli, cloudflare, storage, studio
• pnpm design:shots of /oauth/consent with a real signed request against a throwaway cloudhal studio --base-url http://localhost:8792 at 1440 and 390 px: no sideways scroll, no console errors (screens checked by eye)

Translations: the 18 non-English oauthConsent.<locale>.ts files and the two new core keys are machine drafts awaiting review; reviewed is unchanged in locales.ts.

Review round 1 fixes (security review of #176)

Every item has a suite test that fails on the first commit of this PR (checked by running the new tests against the old production code).

keyId audit (item 4)

Deviation from the review's suggested fixes

• Item 3: the review suggested recording in the provider's consent only the scopes that survived narrowing unchanged. That would drop e.g. content:write from a Contributor's token, and the token must still carry a scope that narrows to the grant's content:draft:own, so the Contributor's agent would lose its draft rights. Instead the provider's consent memory is checked against the grant and the member's current role before every authorize, which forces the screen exactly when the grant would change.
• Item 2, order: with the provider cleanup in the same SQL batch as the grant change, there is no order to get wrong; the authorize check covers anything older.

Checks for this round

One package at a time, D1 included (nothing left to CI):

• @cloudhal/api ✅ 42 files / 523 tests, the OAuth suites 42/42 (21 × better-sqlite3, 21 × Miniflare D1), test/access-token.test.ts
• @cloudhal/agent-runtime ✅ (new credentials.test.ts), @cloudhal/mcp-server ✅ (new embargo case)
• @cloudhal/studio ✅ (new step-up case; i18n tests after pnpm i18n:import)
• packages/cli/test/cloudflare-deploy.test.ts ✅ (the full flow on workerd still passes with the grant claim and the token hash)
• pnpm lint 0 errors, pnpm size:check ✅ (baseline tightened for schedule-tools.ts), pnpm design:lint ✅, typecheck ✅ in api, cli, cloudflare, mcp-server, agent-runtime, studio

Review round 2 fixes (verification of 632cf45)

Each new test fails on 632cf45 and passes now (run against the old production files).

Also: the giveConsent comment now says what a failed provider call leaves on a step-up of a live grant (the approved scopes and mode apply at once, capped by the tokens' own scope claims), and schedule-tools.ts:310 takes the key through agentCredential() (keyOf, gate-approval.ts).

Phase 3 (not in this PR): set_embargo through an OAuth connection saves the embargo but does not file an approval request; it answers with-next-publish. Filing a request (or a grant-bound auto approval, which needs a contract change since the auto approval names a keyId) belongs with "Connected agents" in Phase 3. I didn't post this on issue #144 myself, because posting there was outside what I could do from here. The text is in the session notes for the project manager to post.

Checks for round 2

• Single files first: test/mcp-oauth-server.test.ts 54/54 on better-sqlite3 and Miniflare D1.
• @cloudhal/api: in the full run, 25 D1 cases in api, assets-api, collections-api and roles failed with Miniflare's fetch failed (the local D1 process dropping connections under load). Each of those four files passes on its own (roles 46/46, api 12/12, assets 22/22, collections 12/12); the other 510 passed in the run. Please let CI's run confirm the D1 halves.
• @cloudhal/mcp-server ✅; packages/cli/test/cloudflare-deploy.test.ts ✅ (workerd flow).
• pnpm lint 0 errors, pnpm size:check ✅, pnpm design:lint ✅, typecheck ✅ in api, mcp-server, cli, cloudflare.

Review round 3 fixes (verification of b5968e1)

Checks for round 3

• Single files first: test/mcp-oauth-server.test.ts (64 cases, sqlite and D1), packages/storage/test/migrate.test.ts + do-sqlite.test.ts ✅. Each new case was run against the production files of b5968e1 (the sign-in case also against 632cf45, where it passes).
• @cloudhal/storage ✅. @cloudhal/api: 528 passed in the full run; 17 D1 cases in assets-api, fields-api, rate-limits and roles failed with Miniflare's fetch failed (the local D1 process dropping connections under load, different files than last round). Each of those files passes on its own (22/22, 12/12, 4/4, 46/46). D1 halves left to CI.
• @cloudhal/mcp-server ✅, pnpm lint 0 errors, pnpm size:check ✅, pnpm design:lint ✅, typecheck ✅.

🤖 Generated with Claude Code